The HeatmapColorMap control is a standalone legend component designed to display the color scale used by a Heatmap or Polar Heatmap in SciChart WPF. It provides visual context for interpreting Z-values by showing how numeric values map to colors in the active heatmap's ColorMap.
The control can be used with multiple charts types, such as Cartesian (2D) Heatmap, 3D SurfaceMesh, Polar Heatmap, etc. It is typically bound to the same HeatmapColorPalette instance that is assigned to the Heatmap RenderableSeries, ensuring consistency between the heatmap and its legend.
2D Heatmap
Polar Heatmap
3D Heatmap
ColorMap Property
The ColorMap property defines the gradient used by the legend:
| Heatmap ColorMap property |
Copy Code |
|---|---|
<s:HeatmapColorMap.ColorMap> <s:HeatmapColorPalette Minimum="-70" Maximum="0"> <s:HeatmapColorPalette.GradientStops> <GradientStop Offset="0" Color="Transparent" /> <GradientStop Offset="0.0001" Color="DarkBlue" /> <GradientStop Offset="0.2" Color="CornflowerBlue" /> <GradientStop Offset="0.4" Color="DarkGreen" /> <GradientStop Offset="0.6" Color="Chartreuse" /> <GradientStop Offset="0.8" Color="Yellow" /> <GradientStop Offset="1" Color="Red" /> </s:HeatmapColorPalette.GradientStops> </s:HeatmapColorPalette> </s:HeatmapColorMap.ColorMap> | |
In most scenarios, this should be bound directly to the HeatmapColorPalette assigned to the Heatmap or PolarHeatmap series. By binding these properties, the legend automatically reflects the active color mapping.
Minimum and Maximum
The Minimum and Maximum properties define the numeric range displayed by the legend. These values determine how the color gradient maps to actual data values. They should be set to match or bound to the corresponding Minimum and Maximum properties of the HeatmapColorPalette.
Adjusting Minimum and Maximum changes how Z-values are distributed across the color scale, allowing you to emphasize specific value ranges.
| HeatmapColorMap (Heatmap Legend) control |
Copy Code |
|---|---|
<Grid> <Grid.Resources> <s:GradientStopsToLinearGradientBrushConverter x:Key="ColorsToLinearGradientBrushConverter"/> </Grid.Resources> <s:SciChartSurface x:Name="sciChart"> <s:SciChartSurface.RenderableSeries> <s:FastUniformHeatmapRenderableSeries x:Name="HeatmapRenderableSeries"> <s:FastUniformHeatmapRenderableSeries.ColorMap> <s:HeatmapColorPalette Minimum="-70" Maximum="0"> <s:HeatmapColorPalette.GradientStops> <GradientStop Offset="0" Color="Transparent" /> <GradientStop Offset="0.0001" Color="DarkBlue" /> <GradientStop Offset="0.2" Color="CornflowerBlue" /> <GradientStop Offset="0.4" Color="DarkGreen" /> <GradientStop Offset="0.6" Color="Chartreuse" /> <GradientStop Offset="0.8" Color="Yellow" /> <GradientStop Offset="1" Color="Red" /> </s:HeatmapColorPalette.GradientStops> </s:HeatmapColorPalette> </s:FastUniformHeatmapRenderableSeries.ColorMap> </s:FastUniformHeatmapRenderableSeries> </s:SciChartSurface.RenderableSeries> <!-- XAxis, YAxis, omitted for brevity --> </s:SciChartSurface> <s:HeatmapColorMap Grid.RowSpan="2" Grid.Column="2" Margin="10" HorizontalAlignment="Right" VerticalAlignment="Stretch" Background="{Binding ElementName=sciChart, Path=Background}" BorderBrush="#777" BorderThickness="1" ColorMap="{Binding ElementName=HeatmapRenderableSeries, Path=ColorMap.GradientStops, Converter={StaticResource ColorsToLinearGradientBrushConverter}}" Foreground="{Binding ElementName=sciChart, Path=Foreground}" Maximum="{Binding ElementName=HeatmapRenderableSeries, Path=ColorMap.Maximum}" Minimum="{Binding ElementName=HeatmapRenderableSeries, Path=ColorMap.Minimum}" Opacity="0.8" Orientation="Vertical" TextFormatting="0.00"/> </Grid> | |
TextFormatting
The TextFormatting property controls how numeric labels on the legend are displayed. It accepts standard .NET numeric format strings, enabling control over decimal precision, scientific notation, or other formatting rules.
For example, specifying a format such as 'N2' displays values with two decimal places. This property ensures consistency between legend labels and other chart components.
Orientation
The Orientation property determines whether the legend is displayed vertically or horizontally. A vertical orientation is commonly placed beside the chart, while a horizontal orientation is typically positioned above or below the chart surface.
EnableAxisDrag
The EnableAxisDrag property enables interactive adjustment of the color scale using the mouse. When enabled, users can drag the legend axis to dynamically modify the Minimum and Maximum values. This effectively changes how data values are mapped to colors, allowing real-time exploration of different intensity ranges. This behavior is enabled by default.
AxisStyle and Advanced Customization
The HeatmapColorMap includes a fully customizable axis that can be styled similarly to a SciChart NumericAxis. The AxisStyle property allows complete control over the appearance and behavior of the legend axis.
Using AxisStyle, you can define custom margins, borders, tick styles, and gridline behavior. You can also provide a custom LabelProvider, apply LabelTemplates, or configure major and minor ticks. This enables full integration with existing chart styling conventions.
| HeatmapColorMap Styling |
Copy Code |
|---|---|
<s:HeatmapColorMap Grid.Column="1" HorizontalAlignment="Right" VerticalAlignment="Stretch" BorderThickness="0" Background="{StaticResource ThemedTransparentChartBackground}" ColorMap="{Binding ColorMap.GradientStops, Source={x:Reference HeatmapRenderSeries}, Converter={StaticResource ColorsToLinearGradientBrushConverter}}" Maximum="{Binding ColorMap.Maximum, Source={x:Reference HeatmapRenderSeries}}" Minimum="{Binding ColorMap.Minimum, Source={x:Reference HeatmapRenderSeries}}" Orientation="Vertical" EnableAxisDrag="True" TextFormatting="0" Margin="20"> <s:HeatmapColorMap.AxisStyle> <Style TargetType="s:AxisBase"> <Setter Property="Margin" Value="-12,0,0,0"/> <Setter Property="BorderThickness" Value="1,0,0,0" /> <Setter Property="BorderBrush" Value="#93A3C5"/> <Setter Property="DrawMinorTicks" Value="False"/> <Setter Property="MajorTickLineStyle" Value="{StaticResource AxisTickStyle}"/> </Style> </s:HeatmapColorMap.AxisStyle> </s:HeatmapColorMap> | |
For comprehensive information about axis styling, label customization, and the LabelProvider API, refer to the SciChart documentation on Axis Styling and Axis Labels.
Integration with LegendModifier
The HeatmapColorMap control can be integrated with the LegendModifier to take advantage of built-in legend positioning capabilities. This is achieved by placing the HeatmapColorMap inside a ControlTemplate and assigning it to the LegendModifier via the LegendTemplate property.
This approach is demonstrated in the “Daily Max Temperature Heatmap” demo